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NTRODU CTION 


FORTRAN has long been regarded as the programming language most suited 
to scientific and numeric applications. FORTRAN 77 is the latest standard¬ 
ised version of the language. This manual describes the use of Acomsoft 
FORTRAN 77 for the Archimedes personal workstations; note that it is not a 
tutorial. 

The Acomsoft FORTRAN 77 compiler has been fully validated in confor¬ 
mance with the American National Standard Programming Language FOR¬ 
TRAN X3.9-1978 (ANS FORTRAN). Detailed language specifications are 
given in the publication American National Standard Programming Language 
FORTRAN, X3.9-I978 which is available from the Bntish Standards Insti¬ 
tute. Less technical approaches arc provided in A Structured Approach to 
FORTRAN 77 Programming by T M R Ellis, published by Addison Wesley, 
and A Pocket Guide to FORTRAN 77 by Clive Page, published by Pitman. 

From now on, unless otherwise stated, or made obvious from the context, 
FORTRAN 77 is taken to mean the Acomsoft implementation of FORTRAN 
77 for the Archimedes personal workstations. 

CONVENTIONS USED IN THIS MANUAL 

The following conventions ate used throughout this manual: 

• Text entered by the user and text as it appears on the screen are shown like 


• Arguments to commands and options are shown as follows; 

The user should enter the chosen value for a rgumen ts. 

• Optional arguments are shown in square brackets. 

SETTING UP YOUR MACHINE FOR FORTRAN 

The Fortran 77 system docs not run under the desktop or BASIC. 

If you are using the desktop, exit by selecting the appropriate icon. You should 
see a prompt consisting of a single *. You can select a normal black and white 
colour scheme by entering BASIC and changing the screen mode: 
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DIRECTORY STRUCTURE 


The Fortran 77 system consists of a compiler which converts Fortran programs 
to machine code, a linker which combines compiled programs with the Fortran 
library into executable images, and a number of command files which arc used 
to run the compiler and linker. These command files assume the following 
directories: 

07: contains Fortran 77 source files. 

aof: contains machine code files produced by the compiler. 

rmp: temporary scratch files produced during the compilation process. 

In addition, the directories Library and Exedib are used to hold the standard 
parts of the system. 


INSTALLATION 


Fortran 77 may be used with a variety of disc configurations. Iastallation 
instructions for the simplest cases arc given below. 

Before doing anything else, make a backup copy of the distribution disc and 
keep the original somewhere safe. To make the copy, ensure that the original 
is write.protected (by sliding the tab to uncover the hole) and then type: 


•backup 0 0 q 

You will be prompted for the source and destination discs. 
The Fortran 77 release disc contains the following files: 


InstallHD Utility to install system on hard disc 

InstallNET Utility to install system on network file server 


Library.07 

Library.07fe 

Library.07cg 

Library.link 

Library.link07 

Library.lpe 

Library.lib.07 


Program for 07 command file 
Fortran 77 compiler, part one 
Fortran 77 compiler, part two 

Program for Iink07 command file 
Floating point emulator 
Fortran library 


Exec lib.07 07 command file 

Exectib.Unk07 Iink07 command file 


F77.edate Example program for debugger session 

F77.HelloW Simple test program 


The following tree displays the! 


structure of the disc mote graphically: 





Operating system variables 

The Arthur operating system uses several string istriablts to control the running 
of programs. One of the most important is RunJPath, which is used as a list of 
directories to be searched for a program. In addition, the Fortran 77 system 
uses three special variables to specify the location of standard files. These arc: 
F77$Execlib: The directory containing the standard command files f77 and 
Iinkf77. The default if this variable is not set is $.Excclib. (the directory 
$.Execlib on the current disc and filing system). Note that the directory name 
includes a final full stop. If the command files are not on the current disc or 
filing system, F77$Execlib must he set so that the command processor can 
locate them. For example, if the files have been moved to a network file 
server, the variable could be set as follows: 

♦set F77$Exec Lib net:*.Execlib. 

F77$Library: The full name of the directory containing the standard Fortran 
library. The default if the variable is not set is $. Library, lib. f77. 

F77$Tmp: The directory used for temporary scratch files created during the 
compilation process. The default is $.Tmp. (again, note the final full stop in 
the value). This is suitable for most configurations. If you arc using the system 
on a shared network file server, you must have a private tmp directory, since 
$.Tmp would be common to all users. In this case, you should set F77$Tmp as 
follows: 

♦set F77ST«p tup. 

Scratch files will then be created in tmp in your current directory. 

Single floppy disc 

The Fortran 77 system can he used with a single 800K floppy disc. Prepare a 
disc by making another copy of the distribution disc. You should then delete 
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unwanted tiles (such as the installation utilities and example programs) to 
maximise the free space on the disc. You will also need to install a suitable 
editor (such as Twin) by copying it from another disc. 

You will tind that you have about 300K free on the disc. This is adequate for 
developing modetately-sized programs. You should not attempt to store too 
many programs on a single disc. You should also ran ‘COMPACT occasion¬ 
ally, to ensure that the disc space is not badly fragmented. If you need mote 
space, object files resulting from compilation may be copied on to another disc 
containing the linker. 

The default settings of F77$Hxeclib, F77$Ubrary and F77$Tmp are suitable for 
a system with a single floppy disc. 

Two floppy discs 

If you have a system with dual floppy drives, you can keep the F 
system on the first disc and your programs and data on the second 
copy of the distribution disc (using the ‘BACKUP command again) 
as the system disc in drive 0. You will also need to copy a suitable ed 


m 














With these settings, the command files and Fortran library will be read from 
the file server, and scratch files will be created in the subdirectory tmp. 

You must create f77, aof and tmp directories in your current net (or floppy) 
directory before using the system. 

When installation is complete, you can prepare a IBoot file to perform 
standard initialisation operations whenever you turn the machine on (or 
whenever you log in to a file server). 

The Fortran initialisation procedure should: 

• Load the floating point emulator if it is not already resident. 

• Set the command search path (RunSPath) if you are using a non-standard 
disc configuration. 

• Set the Fortran operating system variables if necessary. 

The required commands can be entered into a IBoot file on your boot disc. If 
you are using a network file server, the boot file is called lArmBoot, rather 

For example, if you are using a hard disc or single floppy system, then all you 


• BUILD !I 










If you are setting up a network system, then the ! Arm Boot tile in your net 
directory should contain: 
set RunSPath ,X.,netArthur11b. 
set F77SExectib net:*.Exec 11b. 
set F77*Library net:*.Arthurlib.Iib.f77 
set F77$Tmp tap. 

On a disc system, !Boot will be run automatically when you turn your machine 
on if you enter the following commands: 


•OPT 4,3 
•CONFIGURE BOOT 

On a network system, ! Arm Boot will be run automatically when you log into 
the file server if you enter: 


If you arc using a system with a single floppy drive, you will need to set up a 
I Boot file on each Fortran disc that you use. 

If you use Fortran only rarely, you may not wish to dedicate the IBoot file on 
your disc for initialising the Fortran system. Instead, you can create an exec 
file which you obey whenever you wish to use Fortran. 


CHECKING THE INSTALLATION 


When you have completed the installation, you can check the system by 
compiling and running a simple program. Either enter a new program or copy 
the demonstration program (77.HelloW from the distribution disc (if you have 
installed on a hard disc or single floppy disc, f77.HelloW will already be 
there). The demonstration program F77.edate is for use in a sample ASD 
(Arthur Symbolic Debugger) session and has a deliberate bug - do not be 
surprised if the results it produces are not correct! 

Compile the program by typing: 


You should see messages like: 

Topexpress FORTRAN 77 front end version 1.1* 
Program WORLD Compiled 
Total workspace used 6016 

ARM FORTRAN 77 code generator version 1.62 
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Main program (WORLD): code 104; data 20 
Total code size: 104; data size: 20 
The version numbers may be slightly different in the programs on the 
distribution disc. 

Unit the program by typing: 

Unkf77 hellow 

The linker should run without any messages. The linked program may be run 
by typing: 
hello* 

You should see the output: 

If there arc any problems, it is possible that the Installation was not completed 
correctly. Check the following points: 

e It you get errors like 'Motjke'. sou .ire probably trying u. run the Fortran 
system inside BASIC. Exit from BASIC by typing QUIT and try again. 

• If you get ‘Bad command' errors, the tun path (RunSPath) may not be 
correct for your configuration. You can display its current value by typing: 

show RunSPath 

Note that directory names in the path must end with a foil stop. 

• Check that the Foil tan system variables are correct. A message like 



indicates that F77$Execlib has not been set correctly or that the files in 
S.Execlib have not been installed property. A message like 
f77: can't open work file" name" 
indicates that F77$Tmp has not been set correctly or that the tmp directory 
(usually $.Tmp) has not been created. 

Note that the values of F77$Execlib and F77$Tmp should both end with a 
foil stop. 

MISCELLANEOUS POINTS 

The two parts of the Fortran compiler can be tun separately. This is explained 
in more detail in the next chapter, ‘The Compiler'. For the HelloW program, 
this could be done as follows: 





HE COMPILER 


The FORTRAN 77 compiler is made up of two parts: a front end which 
checks that the source code conforms to the standard, and a code generator 
which creates the equivalent machine codeprogram. This is in Acom Object 
Format (AOF) and is linked into an executable form using the linker program. 
Command files are normally used to perform a compilation and to link. There 
are a number of arguments which can be issued to give extra control over the 
compilation and allow options to be specified. 

The command (77 executes a command file which runs the two parts of the 
compiler in sequence, and so compiles the program without the need for the 
user to give two separate commands. 

You can write your own command files for running the Fortran compiler with 
a different set of arguments. If you do this, it is advisable to use a different 
command name and leave f77 consistent with the examples in this manual. 
Instructions for writing new command files are given in Appendix C. 

To run the two parts of the compiler and the linker separately, the command 
f77fe is used for the front end, f77cg is used to generate the machine code, and 
link is used to link AOF files into executable programs. 


COMPILATION ARGUMENTS 

The f77 command compiles a single source file to object form. The format of 






in the -< 


Several options are accepted by the compiler. These are given 

argument. The options available are listed in the next section, Compilation 


-object name 

By default, the AOF output is written to the file aol .name, where name is 

the source file name. The -object argument can be used to direct the 

output to another file in the aof directory (the name given is prefixed with 
'aoif.' before use). 

The -debug argument controls the amount of symbolic debugging 
information included in the AOF file for use with ASD, the Arthur Symbolic 
Debugger. (Note that Appendix F contains a sample ASD Fortran session). 
The level should be one of the following: 
none No information. This is the default. 

■ in Subroutine and function names only. 

vars Subroutine and function names, and variable name information, 
tines Subroutine and function names, and line number information, 
all Subroutine, function, variable and line information, max is a 
synonym for all. 

Normally, none is used for a working pmgram and a 11 for programs under 
development. The full information is quite bulky and so should be avoided 
when not debugging. The intermediate levels can be used to provide some 
debugging assistance whilst saving space. 

-id 

The - id (or- identify) argument causes the f77 command to display the 
vetsion number of the FORTRAN 77 system. 

The special keyword -help can be used to obtain a summary of the 
arguments expected by the f 77 command: 

177 -help 
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Example compiler commands 

The mininuil command 
f77 Fprog 

All source files by default reside in a subdirectory called ‘f77\ This command 
therefore compiles the source program f77.Fprog. The output will be 
directed to aof. Fprog. 

Error messages are sent to the VDU. Default compilation options are used. 
Redirecting the object file and using compiler options 
f77 Fprog -object Fred -opt +6 

This compiles F77.Fprog producing the object file aof .Fred using the 
FORTRAN 66 option. 

177 prog -debug all 

Compile f 77 prog to AOF in aof .prog, with full debugging Information 
included, 
f77-help 

Display summary of arguments and options. 

177 prog2 -object ttr -debug pin -id 

Compile f77.prog2 to AOF in aof .zee, with minimal debugging 
information. The FORTRAN 77 version number is displayed. 

COMPILATION OPTIONS 

The -opt argument is followed by a list of compilation options (in upper or 

The options B, H, T. 6 and 7 are enabled ot disabled by preceding them with 
+ or -. The options X, L and W must be followed by a number. The 
default for the ful( set of options is: 

This means that code generator line numbering is set to level I: level 2 
warning messages are given; there is no cross-referencing output, no bound 
checking, and Hollerith constants ate not allowed; tracing and FORTRAN 66 
are disabled. 

The options have the following meanings: 
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B Causes the compiler to generate bounds checking code. Array or 
substring subscripts out of range will cause run-time enors to be 
reported in programs compiled with this option. 

H When enabled, this option allows Hollerith constants to be used in 
DATA statements to initialise non-character variables (for example, 
INTEGER). 

L n This option is followed by a number which indicates the level of line 
numbenng included in the code for backtrace purposes (see the chapter 
entitled Emirs and debugging). The levels available are: 

• 0 no line numbering 

• 1 numbers lines containing subptogramcalb 

• 2 statements which can cause a run-ttmc exception 

• >2 numbers every line 

Higher levels cause mote code to be generated. If a hardware exception 

occurs in a module compiled with level I, the backtrace system will not 

he able to determine the exact line number; instead a range of numbers 
will be given (for example. 1001106). The error will lie in this range. 
6 This option allows FORTRAN 66 feature to be used; if enabled, it 

implies the H option. When set, most constructs which have different 

meanings in the two versions are interpreted according to the 
FORTRAN 66 definition. In particular: 

• DO loops will always execute at least nice. 

• Hollerith (nH) constants are allowed in DATA and CALL 
statements, and quoted constants in calls are not of CHARACTER 
type. 

• Non-CHARACTER array names are allowed as format specifiers. 
When the FORTRAN 66 switch is used, Hollerith and quoted 
constants are treated in the same way when used as arguments in 
CALLS - they are not of CHARACTER type. The option is provided 
for use with FORTRAN 66 programs which store character information 
in numeric data types. 

For example, the following calls will have identical effects at run time if 
the FORTRAN 66 switch is used: 
call jin('abed') 
call jin Uhabcd) 
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B HE COMPILER 

If the FORTRAN 66 switch is set, run-time FORMATs specifiers may 
also be non-CHARACTER array names. 

For example: 

double precision d(3),nun 

data d<1>, d<3> /8h (IX,020., 5h,I5/>/ 

data nui /ZhIO/ 

d(2>= nun 

write (6, d) Z.3d0, 10 


This facility was introduced to assist in the implementation of 
FORTRAN 66 programs, it is strongly recommended that new 
programs use CHARACTER formats. 

T This causes the compiler to plant tracing code in the output file. The 
+T switch causes the front end to embed calls to special trace routines 
at various points in the program, such as program unit entry, DO 
statements, labelled executable statements and subprogram calls (see 
the chapter entitled Emm and debugging). 

Wn This sets the warning message level. A following digit of 0-4 is 
interpreted from the zero level as ‘suppress all warnings’ to 'print all 
warnings' (level 4). See the chapter entitled Errors and debugging for 
more details. 

Xn This is followed by a cross-reference listing width of 18 or mote for 
maximum legibility. A value of zero suppresses cross-referencing. The 
upper limit depends upon the device to which the listing is being sent 
(for example, the printer). Cross-reference information is given 
immediately after the END statement of a program unit. For each 
name, the type is given, together with the lines on which it is 
referenced. For each statement label, the type (executable or non¬ 
executable) and the line number of the statement is given, as well as 
the lines on which the label is referenced. 

7 This option is used to control warnings about the use of FORTRAN 77 
language extensions. If unset, warnings are not produced; if set, 
messages are produced when the warning level (Wn) is 2 (the default) 
or greater. The option is unset by default, so that the extensions may be 
used without messages, whatever the warning level. 


17 


COMPILING IN SEPARATE STAGES 


As an alternative to using die f77 command to execute a command file that 
runs both parts of the compiler, the front end and the code generator can be 
run separately. This section gives details of how to do this. 


The front end (f77fe) reads a FORTRAN 77 source program and converts it to 
a special intermediate form known as FCODE. 

The options handled by the front end ate X, W, T, 6 and 7. The default 
settings are XOW2-T67. 

Command format 

The front end has the following command format: 
f77fe C-froiO file C-to file] C-lfst file] 

C-opt options] C-ver file] 

FORTRAN 77 source program. 

FCODE output file. If this argument is not quoted, no FCODE is produced, 
-list 

Listing file. If LIST is quoted, a listing of the source program with line 
numbers is sent to the file, together with any error messages. Otherwise error 
messages are sent to the initial output stream, and no listing is produced. 

Front end option string. The options available were described in the section 
entitled Compilation upturns. 

Output file for compiler messages and errors; if omitted, output is to the 
terminal. 

The special keyword -help can be used to obtain a summary of the 
arguments expected by the front end: 

17Tfe -help 
Examples 

f 77f e f77-prog -to tep.fcode 

Compile source program in f77 prog to FCODE in tmp.fcode. 




The code generator has the following command format: 
f77cg C-fcode] ffleC-to file! C-as« file1 C-ver 


Object output file. If this argument is not quoted, no object file is produced. 
The object file is in an AOF file, and may be linked with other AOF files 
using the linker Link to produce an executable file (see the chapter entitled 
Using the Linker). 


Output file for code generator messages and errors; if omitted, output is to the 







Option string. The options available have already been described. 


The file used for the code generator map output. The map gives the name, 
type and location of local and COMMON variables in each program unit. 
The location is relative to the start of the static area for a local variable and is 
the offset in the block for a COMMON variable. The offset of each statement 
number from the start of the code is also given. 

Level of debug information. The levels available have already been described. 

Name of FORTRAN source file to be included in debugging information. Not 
used if the debug level is none (the default). 

The special keyword -help can be used to obtain a summary of the 
arguments expected by the code generator: 


Examples 

f 77cg tap.f code -to aof .prog 

Generate code from FCODE in tmp.fcudc to an object file in aof.prog, 
f 77cg tsip.prog -asm vdu: 

Code generate tmp.fcode, sending assembler output to the terminal. 

Code generate as before, but also send map output to map. prog. 

f77cg tmp.fcode -to aof .prog -opt *b 

Code generate with bound checking code inserted. 

f77cg tmp.fcode -to aof .prog -debug all -source f77.prog 

Code generate with full debugging information, with the FORTRAN source 

specified as f77.prog. 


LINKING AND EXECUTION 


A compiled FORTRAN program is linked using the standard Archimedes 
linker. The FORTRAN 77 library file should be quoted as one of the input 
files, using the library qualifier / I. The resulting program is run in the normal 


ik command sequence as fo 
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The linkf77 command sequence uses value of the system variable F77$Libtary 
as the name of the FORTRAN library file. If the variable has not been set, the 
default name is S. library. Iib.f77. The variable should be set if the library has 
been stored on a different disc or filing system. For example, if the library is on 
a network file server: 

set F77*L1brary net :$. Arthur lib. 11 b.f 77 

The linkf77 command sequence is for simple links and may be adapted for 

more advanced requirements. The basic form of a FORTRAN 77 link is: 

The linker may be used to combine a number of FORTRAN object modules to 
a single executable flle.The general form of the command is: 
link aof.aodl aof.nodZ ... $.library.lib.f77/l -output 
prog 

Here, modi, aodZ, etc. ate the object modules and prog is the executable 








XTENSIONS TO THE STANDARD 


Acorn FORTRAN 77 offers several enhancements to the standard, which are 
described in this chapter. To get a warning that the extensions described in 
this chapter have been used, use the 7 option when compiling (see the chapter 
entitled The compiler). Further extensions concerning input/output are 
described in the chapter entitled Input/oulput. 


HEXADECIMAL CONSTANTS 


?<type> <digits> 

<type> is a letter, specifying the type of the constant. It must be one of 1, R, 
D, C, L, H, or Q (for INTEGER, REAL, DOUBLE PRECISION, 
COMPLEX, LOGICAL, CHARACTER and COMPLEX* 16, respectively). 
The <type> letter is followed by hexadecimal <digits> (0-9, A-F). There 
must always be an even number of digits (that is. an exact number of bytes). 
The bytes in a CHARACTER hexadecimal constant are given in the order in 
which they are to appear in store. With other constants, the most significant 
byte is given first. If the type of the constant is REAL, DOUBLE 
PRECISION, COMPLEX or COMPLEX *16, the number of bytes must 
match the site of the item in store (4, 8 or 16); for INTEGER and LOGICAL 
constants, there may be fewer bytes. For example: 

CHARACTER WINDOW * C*> 

PARAHETER (WINDOW = ?H1C05141E0C> 

J = 7X1234 

Here, WINDOW consists of the bytes 1C 05 14 IE OC, and J is set to the 
decimal value 4660. 


In Acorn FORTRAN 77, all lower-case letters (except in FORMATS and 
character constants) are converted into upper case upon reading the source, so 
all statements, identifiers and so on may be in lower case. Names may be up to 
255 characters long. It is worth noting, to save confusion, that there is no 
limit on the length of CHARACTER values. 


LOOPS 


WHILE... END WHILE 
This loop construct has the syntax: 

WHILE (logical expr) DO 

ENDWHILE 

WHILE and ENDWHILE must be nested correctly, and neither statement 
may be used as the terminal statement of a DO—loop, ot in a logical IF. 
The loop is equivalent to: 

11 IF (.NOT. logical expr) GOTO 12 

GOTO 11 

12 

This form of loop is compatible with WATFIV and the Salford FTN77 
compiler for PRIME computers. 

DO WHILE 

This loop construct has the syntax: 

DO nC,) WHILE (logicalexpr) 


The rules regarding nesting and the terminal statement are exactly as for 
normal DO loops. 

This form of loop is compatible with the Fujitsu and VAX/VMS FORTRAN 
77 compilers. 


Block DO 

The syntax of DO and DO WHILE loops has been extended so that the 
terminal statement number may be omitted. The loop is then terminated by 
an END DO statement: 



/2,v3 


Extensions to the standard 

or DO WHILE (logical e>pr) 

END DO 

END DO may not be used as the terminal statement in a labelled DO loop. 
This form of loop is compatible with VAX/VMS FORTRAN 77 and the new 
FORTRAN standard. 

RANDOM NUMBER GENERATORS 

Acorn FORTRAN 77 has two routines for random number generation: 

REAL FUNCTION RND01 O 

returns a pseudo-random number in the range 0.0 r < 1.0 
SUBROUTINE SETRND (I) 

selects a new random sequence. If 1 is reto, the sequence is non-repearable. 
The generator is initialised with a call to SETRND(O) so that successive runs 
will produce different sequences. 

INCLUDE STATEMENT 

An include statement allows a file containing source code to be read in by the 
compiler at the point where the include statement occurs. The syntax for the 
statement is: 

INCLUDE *fi lenaae' 

Line numbers in the include file are not recorded on the object file and will 
therefore not appear in a backtrace; correct line numbers are shown in the 
program listing and error messages. 


TYPE NAMES 

REAL*8 may be used as an alternative to DOUBLE PRECISION. The type 
names LOGICAL»4, INTEGER**!, REAL«4 and COMPLEX*8 are 
synonyms for LOGICAL, INTEGER, REAL, and COMPLEX, respectively. 


COMPLEX* 16 

A COMPLEX* 16 value consists of pair of DOUBLE PRECISION numbers, 
representing the real and imaginary parts of a complex number. The rules for 
the use of COMPLEX* 16 are the same for COMPLEX, with a few exceptions: 
_ 25 


REAL or COMPLEX 



same as for COMPLEX, except that the individual parts ate DOUBLE 
PRECISION, rather than REAL. 


There ate new specific names for intrinsic functions with COMPLEX* 16 
arguments; these names must he used if it is wished to use such a function as 
a subroutine argument. The names are; 


Generic Specific 
ABS CDABS 
CONJG DCONJG 
SQRT CDSQRT 
EXP CDEXP 
LOG CDLOG 
SIN CDSIN 
COS CDGOS 


BIT MANIPULATION FUNCTIONS 


There ate eight intrinsic for 
INTEGER arguments. The fo 
and may also be passed as argi 


cemed with bit manipulation on 
expanded in-line by the compiler 
alls. The functions are. 


IANDfl, J) logical and of I and J 
IOR(I, J) logical or of 1 and J 
IEOR0, J) logical exclusive or of I and J 
NOT(I) logical complement of 1 

ISHFTO, J) return I shifted left J places if J is posttive or shifted right -J 
places if ] is negative. The result is undefined if J is not in 
the range -32 to +32. Bits shifted out at the end are lost; 
zeroes are introduced at the other end. 
return I with bit j set to one. Bit zero is the least significant hit. 


IBSET(I.J) 






1XTENSIONS TO THE STANDARD 

The result is undefined if J is not in the range 0—31 
IBCLR(1, J) return I with bit J set to zero. 

BTESTO, J) test bit J of I and return a LOGICAL result - .TRUE, if the 
bit is set and .FALSE, if it is cleat. 

Note that BTEST returns a LOGICAL result; the other functions return 
INTEGER. 

For example: 

IF (BTESTOX, 0>> ... 

Test to see if IX is odd. 

I-IANDCX,JIFF) 

Clear all but the least significant byte of I. 

1= ISHFTiJ, -24) 

Extract the most significant byte of J. 

RELAXED RULES FOR LIST-DIRECTED INPUT 

When reading a complex value using list-directed (free format) input, an 
integer or real constant can be given - the imaginary part of the value is set to 

When reading a character value, if the constant: 

• does not start with a quote 

• is contained on a single record 

• docs not contain an embedded space, comma or / character 

• does not start with digits followed by a *, 

then the delimiting quotes may be omitted and embedded quotes are not 
doubled. 

ARTHUR INTERFACE ROUTINES 

The FORTRAN tun-time library contains some simple routines to interface to 
the Arthur operating system. These are as follows: 

OS_Byte 

SUBROUTINE OSBYTE UFUNC, IARG1 , IAR62) 



Perform the OS_Bytc function as above with the results (from R1 and R2) 
passed hack in the variables IRES I and IRES2. 





• Tu read a key with a Id-second timeout, with the ASCII code 
going to KEY and the result flag to IF LAG. 

CALL 0SBYTE2 (?I81, HOD (1000,254), 1000/256, KEY, 
+1FLA6) 

OS-Word 

SUBROUTINE 0SW0RD (IC0DE, IARRAY) 

Perform OS_Word fimetion ICODE with parameter block (ARRAY (an 
integer array). 

• To read the current graphics cursor position: 

INTEGER BLOCK (0:1), *, Y 


CALL 0SW0RD (13, BLOCK) 



OS-CLI 





XTENJ 


JSIONS TO THE STANDARD 


OSCU passes the string to the command intcpretcr for execution. The result 
is .TRUE, if the command succeeded and .FALSE, if it failed. In the case of 
an error, the code and corresponding message may be obtained by using: 

SUBROUTINE OSGETERROR (IERRNO , ERRSTR) 

CHARACTER *(*> ERRSTR 

Return the error code and string message corresponding to the last operating 
system error. This should be called immediately after a failed OSCLI call (the 
message space is also used by the FORTRAN IO library). 

For example, to display the contents of a directory: 

CHARACTER*80 DIR, NESS 
LOGICAL OSCLI 


IF (.NOT. OSCLI ('CAT ' // DIR)) THEN 
CALLOSGETERROR (1ERR, MESS) 

PRINT 100, I ERR , NESS 
100 FORMAT < 'Error ', 110, A) 

ENDIF 
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This chapter describes how FORTRAN 77 input and output functions ate 
implemented and how this affects programs. 


UNIT NUMBERS AND FILES 

A FORTRAN unit number is a means of referring to a file. Unit numbers in 
the range I to 60 may be used, as well as the two * units for the keyboard and 
screen. Unit number zero is equivalent to the asterisk units and may be used in 
sequential READs and WRITEs only. Note that your filing system limits the 
number of files you can open simultaneously - consult your filing system 

A unit number may be connected to an external file either by means of an 
OPEN statement or by assignments on the command line when the program is 
tun. If an OPEN statement with the FILE= specifier is used, then the unit is 
connected to the given filename; otherwise, the command line parameters are 

The format of the command line is; 
command {file*} {unit=filc*} 

that is, an optional list of filenames followed by an optional list of assignments 
of a particular unit to a named file. The initial series of unkeyed filenames are 
connected to units 1, 2, 3 and so on. Each keyed file is connected to the given 
unit number. All unkeyed definitions must precede any keyed definitions. 
Examples are: 

PROG ABC DEF 

This associates the file ABC with unit 1 and DEF with unit 2. 

PROG 10= FILE 

This associates the file FILE with unit 10. 

PROG DATA 32 = DATA 3=X 

This associates DATA with unit I, data with unit 32, and x with unit 3. 
The two * units always refer to the screen and the keyboard. Any units which 
are not connected to a file in an OPEN statement or command line 
assignment also refer to these streams. 

The screen and keyboard streams can be redirected to (from) a file using the 
standard Arthur syntax (( > filename } and { < fi l ename }). 


A file accessed with STATUS-SCRATCH (OPEN) or STATUS=DELETE 
(CLOSE) is deleted when the unit is closed. 

All files are closed automatically when a program terminates. 

When writing to a sequential formatted file, a distinction is made between 
files which are to be printed and those which are not. In the former case, the 
first character of each record is taken as a carriage control and does not form 
part of the data in the record. Since any file may eventually be printed, some 
means is required in FORTRAN for specifying whether a given unit is to be 
treated as a printer. This may be done in one of two ways: 

• All units in the range 50—60 assume printer output by default. On other 
units, the FORM=‘PRINTER' option can be used to select printer operation. 

• Quoting FORM='PRINTER' in the first OPEN statement for the unit 
causes printer output to be assumed for that unit. (Note: this is an extension 
to the standard.) 

Note that printer output does not imply output to any physical printer which 
may be connected to the machine. 

The carriage control characters which arc recognised and their representation 
in files arc described in the section entitled Formatted IO. 


SEQUENTIAL FILES 

Opens and closes 

An OPEN statement for a sequential file does not specify the direction of 
transfer that is requited, so the actual system open operation cannot be done 
until the first READ or WRITE statement following the OPEN. For this 
reason, an OPEN statement which refers to a nonexistent file will not fail - 
the error will occur when a READ or WRITE is attempted, but may then be 
trapped by use of an ERR= specifier. 

A sequential unit may be used without an explicit OPEN operation, in which 
case the file is actually opened on the first READ or WRITE which refers to 
the unit. The following subroutine is an example of the use of OPEN and 
ERR=. The routine copies a named file to the terminal, using unit 10. 
SUBROUTINE COPY (FILE) 

CHARACTER FILE* <*>, LINE*72 
OPEN <10, FILE=FILE, ERR-100) 

1 READ (10, ’(A)', END = 100, ERR=100> LINE 
PRINT '(A)', LINE 
GOTO 1 
















The following example program illustrates interaction with a terminal file: 

READ <*,*, END-3) I 
WRITE <*, 2) I, 1*1 
2 FORMAT <2110) 

GOTO 1 


The CHAR (unction may be used to construct bytes for output as VDU 
control codes. For example, the following statements will switch the screen to 
MODE 3 on your machine: 

WRITE <*, 3) CHAR<22>, CHAR<3) 

3 FORMAT (S,2A> 

Note the use of the $ format descriptor to suppress the final newline. 

During formatted input of numeric values, blanks are either ignored or treated 
as zeros, depending on the use of the BZ and BN format specifiers, and the 
BLANK status of the unit. All preconnected units (that is, those opened 
without explicit use of OPEN) have BLANK=ZERO as the default status: any 
unit connected by an OPEN statement has BLANK=NULL as the default. 
The difference in the defaults was introduced for compatibility with 
FORTRAN 66 and the FORTRAN 77 subset language (in FORTRAN 66, 
blanks arc always treated as zeros). 

Unformatted 10 

Unformatted reads and writes are permitted on disc files only. Unformatted 
and formatted operations may not be mixed on any unit, unless the unit is 
closed and reopened. 

Each unformatted WRITE statement writes a single record to the file. The 
record may be read back later by any READ which quotes the same number of, 
or fewer, variables. For example, in: 

WRITE (1) 1, 2, 3, 4, 5 
WRITE (1) 6, 7, 8 



i is to 1 and j to 6. The first record contains 20 bytes of data, and the second 
12 bytes. 




NPUT/OUTPUT 


The desired effect could be achieved by padding all unformatted records to the 
same length, but this would lead to wasted file space in many cases. The 
system includes a record length before every unformatted record when it is 
output, and always reads the right amount when the record is read again. 


ctual format of the length is the characters UF, followed by a four-byte 
ount giving the number of data charactcre following. Thr 
s a check that the file contains valid unformatted records. 
m records written in the example above would contain 


01 00 
55 *6 
06 00 


00 00 00 

00 02 00 00 00 03 00 00 00 04 00 00 00 0! 
0C 00 00 00 

00 00 00 08 00 00 00 


DIRECT ACCESS FILES 


cess file consists of a number of records, all of the sa 
be read and written in any order. The records arc 
r all unformatted. 


An OPEN statement, quoting the record length, is always required when 
using a direct access file. The record length Is measured in bytes, and 
formatted records are padded to this length with spaces. 


A direct access file starts with six special bytes which identify it and give the 
record length. These bytes arc the characters DA followed by the record 
length as a four-byte value (LS byte first). 


a smaller record length 


If the file has been opened for updating or input, the first six bytes of the file 
are read and checked. The OPEN will fail if these bytes are invalid, or the 
specified record length is greater than the value used when the file was 




being delayed to the next READ or WRITE, as is the case with sequential 
OFENs. Therefore, any errors which occur in the open may be trapped by an 
ERR= specifier in the OPEN statement. 

Note that a direct access OPEN may refer to an existing file only if it is of the 
correct format; however, it would be simple to provide a utility program to 
create a new direct access file of a given site and record length. The following 
is an example program which uses direct access to write and read a file on unit 

42: 

OPEN (42,ACCESS^'DIRECT* , FILE= 1 DAFILE 1 , RECL=16, 

+ ERR=100, I0STAT-1 ERR) 

DO 1 J = 20,1,-1 

1 WRITE <42, REC=J> J , J + 1, J*J, J-1 
DO 2 J =1, 10 

READ <42, REC= J ) , K, L, N 

2 WRITE <*, 3) K, L, N 

3 FORHAT < IX, 315) 

STOP 

100 PRINT *, ’OPEN FAIL:', I ERR 


Note that unformatted records are the default for direct access files. The file 
'dafile' used in the above example need not exist already, but if it does, it must 
be a valid direct access file with a record length not less than 16. 


OPEN and CLOSE 


The OPEN and CLOSE statements have been discussed above. The NEW 
and OLD values for the STATUS specifier in the OPEN statement are 


INQUIRE 


INQUIRE by unit 

An INQUIRE by unit operation gives information on a particular unit. The 
EXIST specifier variable is set to .TRUE, if the unit is in the valid range. It is 
Impossible to give accurate re spons es to the SEQUENTIAL, DIRECT, 
FORMATTED and UNFORMATTED specifiers, so ‘YES’ is returned if the 
unit is actually being used for the relevant access type, and ‘UNKNOWN’ is 
returned otherwise. Note that a unit is NAMED only if a FILE specifier was 
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quoted in the OPEN statement for the unit. Command line file assignments 
are not available to INQUIRE. 

INQUIRE by file 

An INQUIRE by file operation gives information on a particular filename. If 
the file has been quoted in an OPEN statement for a unit (and not CLOSEd), 
information deduced from that connection is returned (for example, DIRECT 
is set to ‘YES’ if the file is open for direct access), and the file is assumed to 
exist. Otherwise, if the file exists, the EXIST repl y is . TRUE and the 
responses to the SEQUENTIAL, DIRECT, FORMATTED and UNFOR¬ 
MATTED specifiers are ‘UNKNOWN’. 


BACKSPACE 

BACKSPACE is not implemented. 


The operation of ENDFILE is entirely internal to the run-time system; the 
only effect is to set end of file status and forbid further access to the file. 


REWIND 


REWIND is implemented as 
a REWIND, the file is in 
statement - the system open 
statement. 


, a CLOSE followed by an OPEN. After executing 
a similar state to that arising after an OPEN 
operation is awaiting the next READ or WRITE 


FORMAT DECODING 


Lower case letters 

Lower case can be used instead of upper case everywhere; cases are 
distinguished only In quoted strings and nH descriptors, and In the D, E and G 
edit descriptors (see below). 
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The I edit descriptor can be used to transfer real and double precision values; 
F, E , D and 6 can be used to output an integer value. Note that the external 
form of a value that is to be transferred to an INTEGER list item must not 
have a fractional part or a negative exponent. 

$ and \ descriptors 

A $ or \ descriptor in a format suppresses the final newline when writing to a 


FORTRAN programs can use the full range of Arthur graphics facilities by 
writing control codes to the VDU drivers. The CHAR function is used to 
convert an integer code to a character for output. 

The basic form of a WRITE statement to cenerate eranhics is: 





For example, to change to mode 12: 

PRINT ' ($,2A)*, CHARC22 ), CHAR(12) 

Or to change the palette for colour 1 to refer to colour 6: 

PRINT '<S,6A>‘, CHAR(19)/ CHAR(I), CHAR < 6), 

+ CHAR(O), CHAR(O). CHAR(O) 

Most move and draw operations take a pair t»f 16-bit coordinates. These 
should be output as a pair of bytes. For example, the following subroutine 
provides an interface to the general PLOT command (VDU code 25): 

SUBROUTINE PLOT (TYPE, X, Y) 

INTEGER TYPE, X, Y 

PRINT ' (S,6A) 1 , CHARC25), CHAR(TYPE) , 

4 CHAR(IAND(X,255)), CHAR(ISHFT(X,-8)), 

4 CHAR(IAND(Y,255>>, CHAR(ISHFT(Y,-8>) 


MOVE and DRAW operations are then type 4 and 5 PLOT calls. 

As a simpler alternative to writing the coordinates as four separate bytes, they 
can be output directly as characters, using the extension which allows non- 
character data to be output with the A format descriptor: 

PRINT ' ($,2A,2A2)', CHARC25),CHAR(TYPE), X, Y 
The A2 format descriptors cause the least significant two bytes of X and Y to 
be output a£ characters. The complete PLOT routine is then: 

SUBROUTINE PLOT(TYPE, X, Y> 

INTEGER TYPE, X, Y 

PRINT 1 (S,2A,2A2)', CHAR(25>, CHAR(TYPE), X, Y 

END 
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WARNING MESSAGES 


The W compilation option enables the compiler to give advice in the form of 
warnings: see the chapter entitled The compiler for more details on its use. 
These warning messages ate graded in severity from I (the most serious) to 4. 
and are useful in detecting areas which may cause tire program to behave in 
unexpected ways. 

Level 1 is the most serious, indicating faults such as having a statement that 
cannot be reached because it is unlabelled and follows a jump. Level 2 flags 
the use of extensions to standard FORTRAN 77 that are a potential source of 
trouble (for example, when moving software to another machine). Levels 3 
and 4 are used to indicate items that are legal but in poor style, and thus 
possibly mistakes. The strict FORTRAN 77 option 7 is used to control 
warnings about language extensions. If unset, warnings are not produced; 
otherwise, messages are produced if the warning level (Wn) is 2 (the default) 
or greater. The 7 option is unset by default so that the extensions may be used 
without messages, whatever the warning level. 


CODE GENERATOR ERROR MESSAGES 

Certain compile-time emits cannot be detected by the front end, but are 
reported by the code generator. As these are not always as explicit as front end 
error messages, they are listed in Appendix A with a brief explanation of their 
most likely meaning. The same caveat applies to the interpretation of code 
generator emir messages as applies to that of some front end error messages: 
the emir which is reported and its line number may not directly correspond to 
an error in the program. For example, an army might be declared which is too 
big for the memory. Quite often, one error may spark off the detection of 
many others later on in the program. See Appendix A for a list of code- 
generator error messages. 


CODE GENERATOR LIMITS 

The code generator has certain internal limits on the complexity of each 

program unit. These are: 

code sire 2 Mbytes 

number of labels 4096 

number of local variables 8192 

number of constants 8192 

number of COMMON blocks 2048 

number of external symbols 2048 
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These limits should never he exceeded in practice; it is likely that the code 
generator will run our of store before this happens. 


Sometimes, a program compiles correctly and links without a problem — yet 
when an attempt is made to run the program, an error message is produced. 
These error messages come from the FORTRAN run-time library and take the 
following form; 


followed by a backtrace. 


N is an error number and t ex t is a sentence describing the error. A backtrace 
is, as the name implies, a re-tracing of the steps which the FORTRAN run¬ 
time library has taken In attempting to run the program; each line of 
the backtrace output gives the name of a program unit, the addresses of 
the corresponding static data atea and the line number. The data area address 
may be used in conjunction with the storage map produced by the code 
generator to examine the values of local variables. The address of the data area 
is given in hexadecimal. Note that a name in a backtrace refers to the main 
entry point of the program unit, and so may not be the actual name used in 
a call. 


Example run-time error message and backtrace 
+++ + ERROR 1025: LB input data not INTEGER 


F77.INIT 

F77.I067 

ERR2 


&000100D8 

800010000 

80000FF0* 

&0000F9B4 

&0000F9B0 


In this example, the main program (with default name) has called ERR1, 
which has called ERR2, which has attempted to read an integer using list- 
directed input (the top two names are internal routines in the tun-time 
library). 

The call to ERRI in the main program was on line 6; the call to ERR2 in 
ERR1 was on line 10, and so on. The appearance of line numbers in the 





backtrace is controlled by the compiler L option; level I is the default. See the 
chapter entitled The compiler for details about compilation options. 

If a hardware trap occurs in a program compiled with line number level 1, it 
may not be possible to determine the exact line number. This is illustrated by 
the following trace; 


ABC £00005514 5/16 

F77JIAIN J000054EC 3 

Here, the main program called ABC failed with a hardware trap between the 
lines 5 and 16 inclusive. If the program is recompiled with line level 2, the 
exact number will be displayed. 


Code 1000 errors 

There are a number of simple tun-time emirs producing error messages which 
have an emit number of 1000. (An example of a code 1000 message was given 
in the previous section.) Sec Appendix B for a comprehensive list. 

ARRAY AND SUBSTRING ERRORS 

There arc two errors which may be produced from a program unit which has 
been compiled with the bound checking option (see the chapter entitled The 

++++ ERROR 1050: array bound error 
An illegal array subscript has been used. 

++++ ERROR 1051: substring bound error 
An illegal substring has been used. 
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Errors and debugging 


INPUT/OUTPUT ERRORS 


Input/output errors are those which 
ERR= specifiers m FORTRAN 771 
message and code are produced a 
continues, with the error code avai 


be trapped by use of the END= and 
ments. If these are not used, an error 
scribed below; otherwise, execution 
: by use of the IOSTAT specifier. 


N is the error code; PREFIX describes the IO operation being attem[ 
(which may be OPEN, CLOSE, BACKSPACE. ENDF1LE, REWIND, 
REAIVWRITE) and UNIT is the unit number, with » given tor one of 
asterisk units and 'internal' tor an internal file. The rest of the message g: 
more information about the error. 

End of file on input may be napped with the END= specifier. The IOSTAT 
value in this case is — 1. If END= is not used, then the message end of t i te 
is produced, with code 1000. Other errors may be trapped with the 
ERR=specifier. The IOSTAT value is the corresponding error code, as listed 
in Af>p«mdix B. 


TRACING 



• leaving the program unit 

• a labelled statement is about to be executed 

• the THEN clause of an IF...THEN or ELSEIF...THEN construct is about 
to be executed 

• the ELSE clause of an IF. . .THEN or ELSEIF...THEN construct is about to 
be executed 

• a DO statement is about to be executed 

• another subprogram unit is about to be invoked. 


i s. 








SING THE LINKER 


The Linker is an essential program for anyone develo 
level compiled language on Archimedes personal wo 
to combine the contents of one or more object files ( 
or Assembler) with one or more library files, prodi 


The format of the Link command is: 

Link-output f i(e [options] files 
The files atgument is a list of input files; this is de: 
is the only compulsory keyword. 

Below is a list of the command line options chat the 
these will only be used occasionally. In the descriptio 
frequently-used options are given fust, followed by tl 
usual, capitals are used to denote the alternative 

-Output Name of the linked output file 

-VIA Use a file to obtain (further) inp 

-Case Make matching of symbols case i 








• Usually, at least one library file will be specified in the list. A library is just a 
collection of AOF files stored in a single Acom Library Format file. You can 
call the procedures in the library for one language from programs written In 
another, as long as both languages conform to the ARM Procedure Calling 
Standard and both run-time libraries use the common run-time kernel. For 
example, an assembler program could use the C printf function, as long 
as the C run-time system had been initialised, through the common run- 

• Libraries ditier in,in objeti files in the way the Linker uses them. Object 
files’ symbols arc scanned only once when the Linker attempts to resolve 
external references. Libraries are scanned as many rimes as necessary. If a 
required symbol is found in one of the library’s component files, the whole 
component is incorporated into the output file. 
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Link -OUTPUT p.sieve aof.sieve, ensi lib 
Link -o X.nybesi c aof .bas* lib.f77 


VIA KEYWORD 


Sometimes you may want to link a large number of input files which would be 
tedious to type on a command line, and whose names can't conveniently he 
matched by a wildcard specification. Using the - v i a keyword, you can store a 
list of input filenames in another file and use this to access them. For example, 
suppose you created the file basf i les with the contents: 



If you then used the command: 

• link -o basic -via basf I les lib 

then the files listed in basf i les would be linked, together with the AOF 
file lib. 


CASE KEYWORD 


If you specify - c a s e in the command line, then the Linker will not treat the 
case of letters as significant in identifiers. By default, the identifiers aa i n and 
Ma i n refer to different objects, as they are spelt differently. However, with 
-case set, they are the same identifier. 


BASE KEYWORD 


By default, the base address of the output file of the Linker is 88000. This 
corresponds to the start of application workspace on the Archimedes 
computer. Alternatively, if the -dbug option is given, the base address is set 
to 850000. This is so that the debugger program Dbug can load at 88000 as 
a normal application, and load the file to be debugged above itself. (There are 
other changes when -dbug is given, as described below.) 
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Using the -base keyword, you can set the base address of the output file to 
any desired value. For example, you may want a program to have a high load 
address (as with the -d bug option set), but still be directly executable (which 
a dbug file in AOF format isn't). 

The keyword is followed by a number giving the base address desired for the 
output file, eg -base *80000. -base 256k etc. When this is done, all 
relocatable objects in the input fiies are relocated using that base instead of 
the default. ^ 


VERBOSE KEYWORD 

If you specify - verbose on the command line, the Linker gives a report of its 
progress. A message is printed as each file is opened and as each module is 
being relocated. For example: 


link: 

link: 



aof.basl 
aof.bas2 

ansi libIfpprintf) 


Usually, when an image file is produced, it will execute correctly only at the 
base address given (or the default). This is because the object program will 
contain references to absolute addresses within the data area. Flowever, if you 
specify the -relocatable option, the final program will be 
relocatable. That is, it can be haded and executed at any address. 

This feat is achieved by adding a relocation table and a small program to 
perform the relocation to the final object code. The relocation table is a list of 
offsets from the start of the program to words which need relocating. These 
words are adjusted by the difference between the base address of the program 
and the address where it was loaded. Once the relocation has been performed, 
the program proper starts executing. 

The relocation process is very fast, and once it has been performed, the space 
occupied by the table is available as part of the program’s heap space when it 
starts executing. 
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Note that although this ability can be used to make a program statically 
relocatable, it does not confer true position-independence on the program. 
That is, the program could not be moved in memory once it has started and 
still be expected to work. 


DEBUG KEYWORD 

If a program is linked using the -dbug keyword, an executable image is not 
formed. Instead, an AOF file is created which contains all of the symbols 
found in the original source files: The code segment of the file can be executed 
under the control of a Dbug program, and the contents of the code and 
data segments may be examined (and altered in the case of the data segment). 

PREDEFINED LINKER SYMBOLS 

There are several symbols which the Linker knows about independently of any 
of its input files. These start with the string Image** and, along with all 
other external names containing **, are reserved by Acorn. 

The symbols are; 

ImageSSROSXBase Address of the start of the read-only (program) area 
ImageSSROSSLi mi t Address of the byte beyond the end of program area 
Image**! ISSBase Address of the start of run-time zero-initialised area 
ImageSSZlSSLimi t Address of the byte beyond the zero-initialised area 
ImageSSRUSSBase Address of the start of the read/write (data) area 
ImageSSRWSSt-imi t Address of the byte beyond the end of the data area 
Although it will often be the case, Acorn does not guarantee that the end of 
the read-only area corresponds to the start of the read/write area. You should 
therefore not rely on this being true. 

Note also that programs can reside in read/writc areas, as they sometimes 
contain local writeable data (eg modifiable code), and it is possible to have 
read-only data (eg floating-point constants and string literals in C). 

These symbols can be imported as relocatable addresses by assembly language 
routines that might need them. 

The Linker joins all areas (from all input files) with the same name and 
attributes together to form a single area. It then creates the two symbols 
nameSSBase and name**Limi t to mark the start and end of the area. It is 
an error for two areas to have the same name but different attributes. 
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CODE GENERATOR ERROR MESSAGES 


argument out of range for CHAR 
The intrinsic function CHAR has been used with a 
outside the range 0-255. 


of the given array is negative or exceeds memory site, 
to extend common block <name> backwards 
apt has been made to extend a COMMON block backwards by 
EQUIVALENCE statements, 
th for CHARACTER value 

which Is not positive has been used for a CHARACTER length. 



6 A DOUBLE PRECISION value 's'*too latge for conversion to a REAL. 
DATA statement too complicated 
The variable list in a DATA statement is too complicated, and must be 
simplified. 

^Th/divisor*tnight°he REAL.' 'nTEGER, DOUBLE PRECISION or 
COMPLEX. 


A REAL constant exceeds the permitted range, 
double constant too large 
A DOUBLE PRECISION constant exceeds the permitted range, 
inconsistent epui va lencing involving <name> 

The given variable is involved in inconsistent EQUIVALENCE 
statements. 

A DATA statement implied DO loop has a zero increment. 

The code generator has run out of workspace - the program unit being 
compiled must be simplified. 
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Bad +nP or -nP construct. 

FORMAT - too many opening parentheses 
More than 20 nested opening parentheses (including the first). 

FORMAT - trouble with reversion 
No value has been or written by the repeated part of the format (this would 
cause an infinite loop if not trapped). The following program fragment 









INPUT/OUTPUT ERRORS 


/ a l i d a 


Invalid attribute used in OPEN statement 
The same filename has been used more than one 
BACKSPAC^EW*NrVENDRLE attempted on 

*d previously on tb 

Ji red access without OPEN 
A direct access READ or WRITE has bs 
statement for the unit. 


an OPEN statement. 

: connected fiat direct 


sd without an OPEN 


ss file could i 

ss file could i 


it (without intervening 
at be opened for input (for example, file is 
at be opened for output (for example, file is 


Formatted input file D contains bad logical value. 

Bad number (range or syntax) in formatted I, D, E, F, o 

Bad complex data 

Bad COMPLEX constant in list directed input. 

LD repeat not integer 
Repeat count (r') in list directed input is not valid. 

Syntax or range error in REAL list directed input value. 




DOUBLE PRECISION 


lot LOGICAL 

LOGICAL list directed input vt 


emir in COMPLEX list directed 
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APPENDIX C 

FORTRAN C COMMAND 

The C command is used to execute a command sequence with parameter 


The filename refers to the command sequence. If the file cannot be found in 
the current directory, then the directory J.excclib is tried. Under Arthur, the 
value of the system variable F77$Execlib (if set) is used instead of the default 
directory. The string should include a final dot. 

If the C program is executed under a different name, that name is used for the 
command sequence, and no filename is read from the command line. For 
example, if a copy of the C program is placed in $.library.f77, then the 
command f77 wilt cause the command sequence $.exedib.f77 to be obeyed. 
The C program functions by copying the command sequence to the temporary 
file J.tmp.exec, obeying directives and performing parameter substitution in 
the process. If the current Input is from an exec file, this is appended to the 
temporary file, so that nested command sequences may be used. Finally the 
temporary file is executed by the command: 


Under Arthur, the value of the system variable F77$Tmp (if set) is used 
instead as the directory for the exec file. The string should include a final dot. 
Values for F77$Exedib and F77$Tmp corresponding to the defaults are 
S.exedib. and S.tmp. 


DIRECTIVES 


A line in a command sequence that starts with a dot is a directive. 

The possible directives are: 

. key keys Defines the key string to be used to decode the parameters. The string is a 

series of keyword names, separated by commas. Each keyword may be followed 
by one or more of the following attributes: 


/K:lf argument is present, keyword must be given. 

/S:Keyword is a switch with no value. 

A . key directive must be present if the sequence contains any parameter 
substitution; more than one . key is not allowed. . k is a synonym for . key. 




• key froa/a , to/a/k,opt/k,quick/s 
In this example, the arguments with keywords from and to arc compulsory, the 
keyword to must always be given. The argument opt is optiomd, but the 
keyword must be present if the argument is used. The keyword quick is an 
optional switch. Examples of valid command lines (assuming that the 
command file is called conn) are: 

coin -from f i lei -opt abc -to f i leg 
coma -to f Ue4 f i leJ -quick 
Subsequent directives arc introduced by char rather than dot. 


Set the opening bracket for parameter substitution to ebar. The initial value 


Set the closing bracket for parameter to chat. The initial value is >. 

Set the character used to introduce parameter defaults to char. The initial 


11 Set the default value of the keyword key to val. Only one .default 
directive is allowed fora keyword, and it must occur after the . key directive. 


.default to vdu: 

-def is a synonym for .default 

Concatenate a non-directive line ending in char with the following line. 
There is no default concatenation character. 

Identification string. The string (with leading spaces removed) is output to 
the screen if the keystring contains an ID keyword and — i d is quoted on the 
command line. Note that a . id directive must precede the .key directive. 
Help information line. Several .help lines are allowed: the information 
(preceded by the identification string, if any) is written to the screen if the key 
string contains a HELP keyword and -help is quoted on the command line. 
After writing the help text, the C command terminates. A single leading 
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space is removed from each line of help text. Note that all . he Ip directives 
must precede the . key directive. 

Directives with a space directly after the dot are ignored; they can therefore be 
used as comment lines. 

PARAMETER SUBSTITUTION 

The value of a parameter may be inserted by a reference like: 

The bracket characters may be changed by .bra and . ket directives - see 
above. The value of a set switch (/S) parameter is its name. 

A default value for the key may be specified: 

<key*d.f»ult> 

The default may itself be a parameter reference: 

<key*<keyZSdefault> 

<key$<key2$<key3Sdefault> 


The dollar character may be changed by the .dollar directive. The default 
is used if the key has not been set on the command line or by a -def au 11 
directive. The key name must be in the key string or must be one of the 
following built-in names. 

=DATE The date in the form DD-MMM-YY. 

=T1ME The time tn the form HH:MM:SS. 

=DAYNO The day of the month in the form DD. 

=MONTH The date in the form MMM. 

=YEAR The date in the form I9YY. 

=TMP The standard temporary directory name (possibly set 

from F77$Tmp), with final dot. 

If the system date has not been set. “<unset>” is used. 

Under Arthur, a key name may also be a system variable, such as SYSJTime 
or F77$Execlib. A \ must be used to escape the $ character in such names 
(otherwise it would he treated as the default value prefix). 

For example: 

echo <Sys\ST1ne> <F77\SExec Ub> 
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EXAMPLE 


compile a FORTRAN 


program: 

. Command sequence to coopi le FORTRAN 


.id F77 commend sequence version 1.00 



• help T Tracing tin earning level 

.helpXn Cross reference 


.help Default are: L1W2X0-8T67 

. key f rom/a,object/k,opt/k,id/s,help/s,id=identify/s 
f77fe f77.<f rom> -to <=tmp>f code -opt <optS+> 
f 77cg <*tmp>f code -to aof .<objec t*<f rom> -opt <opt*+> 

Note that ID and HELP keywords are included in the key string. 
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CALLING ASSEMBLER FROM FORTRAN 

This section provides some guidance on the writing of assembler routines to he 
called from FORTRAN. It is assumed that the reader is familiar with 


Register conventions 

FORTRAN programs use a simplified form of the standard Acorn calling 
conventions (as defined in Appendix C of the Archimedes Programmer's 
Reference Manual). The main differences arc that only one argument is passed 
in all calls, and that the registers reserved for register variables (vl-v6 and f4- 
17) are not preserved by FORTRAN subprograms. Thus C programs cannot 
call FORTRAN (because registers are not preserved), although FORTRAN 
can call C. 

The detailed register 
R0-R9 
FP (RIO) 

SP (R12) 

SB (R13) 

Argument lists 

Every call In FORTRAN passes one argument in RO (AI). This is a pointer to 
a list of the addresses of the arguments given in the call (every argument in 
FORTRAN is passed by reference). Thus the address of the first argument is at 
|R0,#0|, the second at [R0,#4|, etc. If an assembler routine does not call any 
other murines, the argument list can be left in RO. Normally, however, the 
address of the list is copied to FP (RIO), which is preserved by calls. 

For a CHARACTER argument, the address in the argument list does not refer 
directly to the data; instead it points at a character descriptor, which is an eight- 
byte block containing the address of the character value in its first word and its 
length In the second. For example, if the third argument in a call is a 
character value, the following code fragment loads its address into RI and its 
length into R2: 

LOR R1,[RO,081 ; Descriptor address 

LDHXA R1,{R1,R2> .-Address and length 

Function results 

For non-CHARACTER functions, the address of the result is passed back in 
RO (ie. the result is stored and the address of the location loaded into RO). A 


Scratch registers. 

Used to refer to argument list within subprogram. 
Standard run-time stack. 

Used to refer to local data within subprogram. 



character function is implemented as a subroutine with the address of the 
result location (as a character descriptor) passed as an extra /rirst argument 
(thus the first argument in the call appears as the second argument, and so 
on). 

A subroutine with alternate returns (*'s in the argument list) is implemented 
as an INTEGER function. The result should be reto tor the main return, one 
for the first alternate return, two for the second, etc The alternate return 
specifiers do not appear in the argument list. 

Static data 

addressed using SB (R13) within the routine (this register is preserved by 
calk). 

Section format 

The code area in a FORTRAN assembler module should start with the routine 
name as a twelve-character string, padded with spaces. The address of the first 
byte after this name Is pushed to the stack during entry. The code area should 
be named F77$$Co<le and have attributes CODE and READONLY. The data 
area (if any) should be named F77$$Dau and have the DATA attribute. 
The basic layout of a FORTRAN assembler section is: 



PC 

FO 


F7 




Eppendix d 


; Data 

AREA IF77$$DataI,DATA 

... data declarations ... 

; Code 

AREA IF77SSCodel,CODE,READONLY 

NAME DCB "modname 

DATAPTR DCD IF77SSDatal ; Address of data 

... code... 


COMMON blocks and NOINIT 

FORTRAN common blocks should be defined as named AREAs with the 
COMMON and NOINIT attributes. An initialised COMMON block 
(equivalent to a BLOCK DATA subprogram) should be defined with the 
COMDEF (common definition) attribute. FORTRAN blank common is 
given the name F77.BLANK. 

Entry and exit sequences 

The standard entry sequence for a FORTRAN-callable routine is: 

ADR R1,NAME+12 

STMFD SP!,{R1,FP,SB,R14> 

LDR SB,DATAPTR ; Address data area 

MOV FP,R0 ; Copy argument list 

NAME refers to the twelve character module name at the start of the section. 
The return sequence is: 

LDMFD SP!,<R1,FP,SB,PC> 

A complete example 

This (rather contrived) example illustrates the use of function results and 
CHARACTER arguments. The FORTRAN 77 equivalent ,.| MM M 
would be: 

INTEGER FUNCTION ICHSUM(CH, ARRAY) 

COMMON /CMAX/ MAX 
CHARACTER *(*> CH 
INTEGER ARRAY(*) 



















A sample FORTRAN program which uses 1CHSUM might be: 
INTEGERX<10> 

COMMON /CHAX/ MAX 

ISUM= ICHSUMC'0123456789 ', X) 



Assuming that the assembler text and FORTRAN test program have been 
typed into the files asm. i chsum and f 77. test respectively, they could be 
compiled and linked as follows: 
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CALLING C FROM FORTRAN 


FORTRAN programs can also call routines written in C. The C procedure has 
to accept a single argument which refers to a list of addresses. A simple way of 
doing this is to dedate the argument as a pointer to a structure containing 
pointer fields. Functions have to be declared as returning a pointer result. As 
an example, a C version of the assembler above might be: 


typedef struc 
♦ ICHSUK (i 


ength;} chardesc; 
: * array;} * args) 


for Cj = 0; j <a rgs -> ch -> length; j ++) 

{ int ich = (args -> ch -> address) Cj3; 



This C (unction has the same specification as the assembler routine except 
that the maximum is not returned in the COMMON variable (C cannot 
access FORTRAN COMMON blocks). Note that the fimetion name must be 
given in upper case. The C procedure could be compiled and linked as follows: 

link aof. test o.ichsuac *. library. Ii b. f 77/1 

$. are. ctib.ansilib/1— image test 
The link command must be typed on one line. Note that both the FORTRAN 
and the C libraries must be given. 
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SAMPLE ASD SESSION 








33 ELSE 

34 BAY « N 

35 MONTH - 'March' 

36 ENOIF 

37 END 

If this program is entered exactly as above and run, the results at first sight 
seem correct - the date tor 1988 (3 April) is right. However, the date shown 
tor 1989 is incorrect - the true result is 26 Match. The result for 1970 is also 
wrong - it should be 29 March. 

To use ASD to investigate this program, it is first compiled and linked with 
debug information included: 
f77 edate-debug all 
11 nkf77 edate 

It is assumed that the source of the program is in f77.edate. To enter the 
debugger, use the following command: 


The first step might be to check that the results are printed correctly. So a 
break point is set on the PRINT statement in the main program (line 7): 
ASD: brk edate:7 

e d a t e in the brk command is the main program name: if the program had not 
started with a PROGRAM statement, the default name F77-MAIN would 
have been used instead. Note that upper and lower case letters in names are 
not distinguished when debugging FORTRAN programs, so the brk command 
above could have been typed in any of the following forms: 

ASD: BRK EDATE: 7 or 
ASD: brk Edate:7or 
ASD: brk EdAtE:7or 
ASD: BRK eDaTe:7 etc. 

The program is run until the PRINT statement is reached and the value of 
DAY is displayed: 

ASD: go 

Program stopped as breakpoint #1, Location edate:7 
ASD: print day 
27 

The value 27 shows that the fault lies in EASTER DATE - the correct result 
is 29. The next step is to trace though the subroutine: 
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